Skip to main content

📡 NetAlertX — Local network device monitor (Docker)

NetAlertX monitors your local network for connected devices and alerts when new, unknown or inactive devices are detected. It's useful to discover unexpected devices on Wi‑Fi or LAN and to keep an inventory of known devices.

This guide provides a clear Docker Compose example for Raspberry Pi, start/stop/update commands, backup/restore instructions, security recommendations and troubleshooting tips.

✅ Prerequisites​

  • Raspberry Pi with Docker and Docker Compose installed
  • The Raspberry Pi must be on the same subnet as the devices you want to scan
  • SSH or local terminal access to the Pi
  • Basic knowledge of Docker and networking

⚠️ Important network note​

NetAlertX needs to see local network traffic to detect devices reliably. For most setups this means running the container with network_mode: "host". Host networking gives the container direct access to the host network (no NAT) and is recommended for correct detection.

📂 Create project folder​

On the Pi run:

mkdir -p ~/docker/appdata/netalertx
cd ~/docker/appdata/netalertx
nano docker-compose.yml

docker-compose.yml (example)​

Create docker-compose.yml with the following content. Adjust the TZ and paths as needed.

services:
  netalertx:
    container_name: netalertx
    image: jokobsk/netalertx:latest
    network_mode: "host"             # recommended for correct device detection
    restart: unless-stopped
    volumes:
      - ./db:/app/db                 # persistent DB
      - ./config:/app/config         # persistent config
    environment:
      - TZ=Europe/Oslo
      - PORT=20211                   # web UI port (used only if not host mode)

Save and exit (Ctrl+O, Enter, Ctrl+X).

🚀 Start, stop and update​

Start the service:

docker compose up -d

Check running containers:

docker ps -a | grep netalertx

Follow logs:

docker logs -f netalertx

Stop and remove:

docker compose down

Update image and restart:

docker compose pull netalertx
docker compose up -d

🌐 Access the web UI​

Example: http://10.10.80.50:20211

🔎 How detection works (notes)​

Detection methods depend on the container implementation. Common techniques include:

  • ARP scans and local network discovery (fast and reliable on same subnet)
  • ICMP/ping checks
  • Port scans or passive observation (if supported)

Because of these methods, NetAlertX must be on the same Layer‑2 network as targets (same VLAN) to detect devices reliably. Running in host mode is the simplest approach.

🔔 Features​

  • Network device discovery and classification (phones, PCs, IoT, printers)
  • Mark and label known devices to ignore expected hosts
  • Alerts on:
    • New device appears
    • Device disappears
    • IP or MAC changes
  • Export logs for audits and history

🔧 Backups & persistence​

Persisted folders:

  • ./db — database and runtime state
  • ./config — user settings and detection rules

Backup example:

cd ~/docker/appdata/netalertx
tar czf netalertx-backup-$(date +%F).tar.gz db config
# copy backup off-host for safekeeping

Restore:

  1. Stop the container: docker compose down
  2. Extract backup into the project folder: tar xzf netalertx-backup-YYYY-MM-DD.tar.gz -C .
  3. Start the container: docker compose up -d

🔒 Security recommendations​

  • Do not expose the web UI to the public internet directly. If remote access is required, use:
    • VPN (recommended) or
    • Reverse proxy with TLS and authentication (Traefik, Nginx) and restrict access by IP
  • Protect your .env and backup files (chmod 600) — they may contain secrets or config.
  • Run the container with the least privileges needed. Host networking is required for detection but avoid exposing sensitive management ports externally.
  • Keep the image up to date: docker compose pull regularly.

📶 Firewall and port notes​

  • If using host mode, the container binds to the host network; ensure firewall rules allow access to the UI port (20211).
  • If port 20211 is in use on the host, either change the host port (when not using host mode) or stop the conflicting service.

Check which process listens on port 20211:

ss -tulpn | grep 20211

🛠 Troubleshooting​

  • Container won't start:
    • Check logs: docker logs netalertx
    • Confirm image downloaded correctly: docker images | grep netalertx
  • No devices found:
    • Ensure container is on the same VLAN/subnet as devices (host mode)
    • Verify the Pi's network interface is up and has IP in the target subnet
    • Inspect container logs for scan errors or permission problems
  • Web UI not reachable:
    • Confirm container is running: docker ps
    • Check port binding and firewall: ss -tulpn | grep 20211
    • If using a reverse proxy, verify proxy config and TLS termination
  • Alerts not delivered:
    • Check notification settings inside NetAlertX and ensure the Pi/container has outbound network access

Useful diagnostics:

docker logs -f netalertx
docker inspect netalertx --format '{{json .NetworkSettings}}' | jq
ss -tulpn

✅ Example quick checklist​

  1. Create folder and docker-compose.yml
  2. Start: docker compose up -d
  3. Approve and label known devices in the UI
  4. Configure notifications and test alerts
  5. Backup db and config regularly

NetAlertX is now installed and ready to monitor your home network. Keep backups, restrict remote access, and run the container in host mode on the same subnet for best detection results.